# SpringValue

Imperative APIs are a great way of animating in response to events, without
the need for component state (ie: render-based updates). In this sense, the
`SpringValue` class is a welcome addition to `react-spring`.

## Intro

Create an animated value. Any type is valid, but only certain types are
actually animated.

The `props` argument can be either..

- a `to` value
- or a set of [`useSpring`](/hooks/use-spring) props.

Types that cannot be animated are basically `immediate: true` animations.
Such types include: a `boolean`, a `display` string like `"none"`, etc.

The animatable types are:

- `number`

```js
new SpringValue(0)
```

- `string` with numbers

```js
new SpringValue('0px 10px')
new SpringValue('rgba(0, 0, 255, 1)')
```

- named colors

```js
new SpringValue('red')
```

- and arrays of the preceding types

```js
new SpringValue([0, '1em'])
```

## Methods

### `get(): T`

Get the current value.

```js
const value = spring.get()
```

### `set(value): this`

Set the current value, replace the `goal` value, and stop animating.

```js
spring.set(1)
```

### `update(props): this`

Add an update to the `queue` array. All updates in the `queue` are
applied at the same time.

```js
const delays = [0, 100, 300]
for (const delay of delays) {
  spring.update({ x: delay })
}
spring.start()
```

⚠️ This method may be deprecated soon.

### `start(): Promise`

Process the `queue` array and replace it with an empty array.

The returned `Promise` resolves after every animation triggered by
the `queue` array has either finished or been cancelled.

```js
await spring.start()
```

The awaited value is an [`AnimationResult`](/common/props#animation-result) object.

### `start(props): Promise`

Process the given `props` object.

The returned promise is resolved after the animation is finished or cancelled.
If a `start` call triggers no animation, the promise resolves immediately.

```js
await spring.start({ from: 0, to: 1 })
```

### `start(queue): Promise`

Process the given array of updates.

The returned promise resolves to an [`AnimationResult`](/common/props#animation-result) object whose:

- `finished` property is only `true` when every animation triggered by
  the `queue` was finished before being stopped or cancelled.

- `cancelled` property is only `false` when all updates in the `queue` were
  never cancelled.

```js
// prettier-ignore
await spring.start([
  { from: 0 },
  { to: 10 },
  { to: 20, delay: 1000 },
])
```

### `finish(): this`

Jump to the goal value immediately.

The `onStart` prop is called whenever `finish` is called before the first
frame. The `onRest` prop is called with `finished: true` as expected.

```js
spring.finish()
```

### `finish(value): this`

Jump to the given value immediately, and call the `onStart` and `onRest`
props the same way `.finish()` does.

```js
spring.finish(100)
```

Fluid values (eg: other `SpringValue` objects) can also be passed.

### `stop(): this`

Stop animating and cancel any delayed updates.

The `goal` value is replaced with the current value.

```js
spring.stop()
```

### `reset(): this`

Restart the animation using its cached `from` and `to` values.

```js
spring.reset()
```

Equivalent to a `.start({ reset: true })` call.

### `advance(dt: number): boolean`

Advance the current animation by the given `dt` (in milliseconds).

_You will probably never call this._

```js
// Advance a single frame.
spring.advance(1000 / 60)
```

### `is(phase: string): void`

Check for the given phase.

```jsx
if (spring.is('PAUSED')) {
  return
}
```

Valid phases include:

- `CREATED` The spring has never animated since being created.
- `IDLE` The spring is done animating.
- `ACTIVE` The spring is animating.
- `PAUSED` The spring was animating but is now paused.
- `DISPOSED` The spring can no longer animate.

## Properties

### `key?: string`

The name given to the `SpringValue` object by its owner.

For `Controller` objects, the `key` of each `SpringValue` is the property name
from either the `to` or `from` object prop.

When defined, the `to` prop can be an object with this `key` defined as
a property.

```js
spring.key = 'foo'
spring.start({ to: { foo: '180deg' } })
```

### `get idle(): boolean`

Returns `true` when both:

- the current phase is _anything but_ `ACTIVE`
- no async `to` prop is active

Put simply, it's `true` when not animating.

### `get goal(): T`

The end value of the current animation.

### `get velocity(): number | number[]`

The velocity of the current animation.

### `animation: Animation`

The animation descriptor.

### `queue?: SpringUpdate<T>[]`

The queue of pending updates.

Call `.start()` to flush the queue.
